import { Code, InlineCode } from '~/components/text/code'
import { HelpLink } from '~/components/text/link'
import Note from '~/components/text/note'
import { P } from '~/components/text'
import Endpoint from '~/components/api/endpoint'
import Request from '~/components/api/request'

export const meta = {
  editUrl: 'pages/docs/api/v2/api-docs-mdx/endpoints/teams.mdx',
  lastEdited: '2019-10-17T14:44:04.000Z'
}

## Teams

### Create a team

<Endpoint method="POST" url="/v1/teams" />

Create a new team under your account. You need to send a `POST` request with the desired team slug.

#### Request Parameters

| Key      | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Required | Description                    |
| -------- | ---------------------------------------------------------- | -------- | ------------------------------ |
| **slug** | <HelpLink href="#api-basics/types">String</HelpLink>       | Yes      | The desired slug for the team. |

##### Example Request

<Request
  method="POST"
  url="https://api.zeit.co/v1/teams"
  headers={{
    'Content-Type': 'application/json'
  }}
  auth
  body={{
    slug: 'a-random-team'
  }}
/>

##### Example Response

<Code lang="json">{`{
  "id": "team_LLHUOMOoDlqOp8wPE4kFo9pE"
}`}</Code>

### Delete a Team

<Endpoint method="DELETE" url="/v1/teams/:id" />

Delete a team under your account. You need to send a `DELETE` request with the desired team `id`.

#### Request Parameters

| Key    | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Required | Description                  |
| ------ | ---------------------------------------------------------- | -------- | ---------------------------- |
| **id** | <HelpLink href="#api-basics/types">String</HelpLink>       | Yes      | The desired id for the team. |

##### Example Request

<Request
  method="DELETE"
  url="https://api.zeit.co/v1/teams/team_LLHUOMOoDlqOp8wPE4kFo9pE"
  headers={{
    'Content-Type': 'application/json'
  }}
  auth
/>

##### Example Response

<Code lang="json">{`{
  "id": "team_LLHUOMOoDlqOp8wPE4kFo9pE"
}`}</Code>

### List all your teams

<Endpoint method="GET" url="/v1/teams" />

Get a list of all the team you belong to.

#### Response Parameters

| Key       | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Description                                                                                                               |
| --------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **teams** | <HelpLink href="#api-basics/types">List</HelpLink>         | The list of each team member as described on [Get single team information](#endpoints/teams/get-single-team-information). |

##### Example Request

<Request url="https://api.zeit.co/v1/teams" auth />

##### Example Response

<Code lang="json">{`{
  "teams": [
    {
      "id": "team_ofwUZockJlL53hINUGCc1ONW",
      "slug": "my-team",
      "name": "My Team",
      "creatorId": "2qDDuGFTWXBLDNnqZfWPDp1A",
      "created": "2017-04-29T17:21:54.514Z",
      "avatar": null
    }
  ]
}`}</Code>

### Get single team information

<Endpoint>
  GET /v1/teams/:id
  <br />
  GET /v1/teams?slug
</Endpoint>

Get the information of a specific team, it could be used either passing the `:id` in the URL or the team `slug` as a query parameter.

#### Response Parameters

| Key           | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Description                                              |
| ------------- | ---------------------------------------------------------- | -------------------------------------------------------- |
| **id**        | <HelpLink href="#api-basics/types">ID</HelpLink>           | The team unique identifier. Always prepended by `team_`. |
| **slug**      | <HelpLink href="#api-basics/types">String</HelpLink>       | The team slug. A slugified version of the `name`.        |
| **name**      | <HelpLink href="#api-basics/types">String</HelpLink>       | The name of the team.                                    |
| **creatorId** | <HelpLink href="#api-basics/types">ID</HelpLink>           | The ID of the user who created the team.                 |
| **avatar**    | <HelpLink href="#api-basics/types">String</HelpLink>       |                                                          |

##### Example Request

<Request
  url="https://api.zeit.co/v1/teams/team_ofwUZockJlL53hINUGCc1ONW"
  auth
/>

##### Example Response

<Code lang="json">{`{
  "id": "team_ofwUZockJlL53hINUGCc1ONW",
  "slug": "my-team",
  "name": "My Team",
  "creatorId": "2qDDuGFTWXBLDNnqZfWPDp1A",
  "created": "2017-04-29T17:21:54.514Z",
  "avatar": null
}`}</Code>

### Update team information

<Endpoint method="PATCH" url="/v1/teams/:id" />

Update the information of the team defined with the id. You need to send a `PATCH` request with a body containing the information you want to change.

<Note>
  You need to be <InlineCode>OWNER</InlineCode> to use it.
</Note>

#### Request Parameters

| Key      | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Required | Description        |
| -------- | ---------------------------------------------------------- | -------- | ------------------ |
| **slug** | <HelpLink href="#api-basics/types">String</HelpLink>       | Yes      | The new team slug. |
| **name** | <HelpLink href="#api-basics/types">String</HelpLink>       | Yes      | The new team name. |

##### Example Request

<Request
  method="PATCH"
  url="https://api.zeit.co/v1/teams/team_ofwUZockJlL53hINUGCc1ONW"
  headers={{
    'Content-Type': 'application/json'
  }}
  auth
  body={{
    name: 'My Cool Team'
  }}
/>

##### Example Response

<Code lang="json">{`{
  "id": "team_ofwUZockJlL53hINUGCc1ONW",
  "slug": "my-team",
  "name": "My Cool Team",
  "creator_id": "2qDDuGFTWXBLDNnqZfWPDp1A",
  "creatorId": "2qDDuGFTWXBLDNnqZfWPDp1A"
}`}</Code>

### Get list of team members

<Endpoint method="GET" url="/v1/teams/:id/members" />

Get the list of team members of the team defined in the URL. The response is a list of maps with the following format.

#### Response Parameters

| Key          | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Description                                                |
| ------------ | ---------------------------------------------------------- | ---------------------------------------------------------- |
| **uid**      | <HelpLink href="#api-basics/types">ID</HelpLink>           | The team member unique identifier.                         |
| **role**     | <HelpLink href="#api-basics/types">Enum</HelpLink>         | The role inside the team, it could be `OWNER` or `MEMBER`. |
| **email**    | <HelpLink href="#api-basics/types">String</HelpLink>       | The email address of the team member.                      |
| **username** | <HelpLink href="#api-basics/types">String</HelpLink>       | The username of the team member.                           |

##### Example Request

<Request
  url="https://api.zeit.co/v1/teams/team_ofwUZockJlL53hINUGCc1ONW/members"
  auth
/>

##### Example Response

<Code lang="json">{`[
  {
    "uid": "2qDDuGFTWXBLDNnqZfWPDp1A",
    "role": "OWNER",
    "email": "user-emailgmail.com",
    "username": "some-user"
  },
  {
    "uid": "JJHkdv6NaPOTH88pXn8FEuGz",
    "role": "OWNER",
    "email": "another-user@mail.com",
    "username": "another-user"
  }
]`}</Code>

### Invite user to team

<Endpoint method="POST" url="/v1/teams/:id/members" />

Invite a user to join the team specified in the URL. To use it send a `POST` request with the user email in the body.

<Note>
  You need to be <InlineCode>OWNER</InlineCode> to use it.
</Note>

#### Request Parameters

| Key       | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Required | Description                                                                                               |
| --------- | ---------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------- |
| **email** | <HelpLink href="#api-basics/types">String</HelpLink>       | Yes      | The email address of the user to invite.                                                                  |
| **role**  | <HelpLink href="#api-basics/types">Enum</HelpLink>         | No       | The role of the user to invite, it could be `OWNER` or `MEMBER`. If not defined, the default is `MEMBER`. |

#### Response Parameters

| Key          | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Description                       |
| ------------ | ---------------------------------------------------------- | --------------------------------- |
| **uid**      | <HelpLink href="#api-basics/types">ID</HelpLink>           | The ID of the invited user.       |
| **username** | <HelpLink href="#api-basics/types">String</HelpLink>       | The username of the invited user. |

##### Example Request

<Request
  method="POST"
  url="https://api.zeit.co/v1/teams/team_ofwUZockJlL53hINUGCc1ONW/members"
  headers={{
    'Content-Type': 'application/json'
  }}
  auth
  body={{
    email: 'user@mail.com'
  }}
/>

##### Example Response

<Code lang="json">{`{
  "uid": "kr1PsOIzqEL5Xg6M4VZcZosf",
  "username": "an-user"
}`}</Code>

### Change user role or status

<Endpoint method="PATCH" url="/v1/teams/:id/members/:userId" />

Change the role or status of an user inside a team member. To change it send a `PATCH` request, if the change is done you will receive a 200 status code with an empty body.

<Note>
  You need to be <InlineCode>OWNER</InlineCode> to use it.
</Note>

#### Request Parameters

| Key          | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Required | Description                                                       |
| ------------ | ---------------------------------------------------------- | -------- | ----------------------------------------------------------------- |
| **role**     | <HelpLink href="#api-basics/types">Enum</HelpLink>         | No       | The new role of the team member, it could be `OWNER` or `MEMBER`. |
| **rejected** | <HelpLink href="#api-basics/types">Boolean</HelpLink>      | No       | Whether the team member is prevented from ever joining the team.  |

##### Example Request

<Request
  method="PATCH"
  url="https://api.zeit.co/v1/teams/team_ofwUZockJlL53hINUGCc1ONW/members/kr1PsOIzqEL5Xg6M4VZcZosf"
  headers={{
    'Content-Type': 'application/json'
  }}
  auth
  body={{
    role: 'OWNER',
    rejected: true
  }}
/>

### Remove user from team

<Endpoint method="DELETE" url="/v1/teams/:id/members/:userId" />

Remove the specified user from a team.

<Note>
  You need to be <InlineCode>OWNER</InlineCode> to use it and the user{' '}
  <b>must not</b> be an owner themselves.
</Note>

##### Example Request

<Request
  method="DELETE"
  url="https://api.zeit.co/v1/teams/team_ofwUZockJlL53hINUGCc1ONW/members/kr1PsOIzqEL5Xg6M4VZcZosf"
  auth
/>
